Skip to content

(0.5) Deprecate legacy pending HTLC ChannelManager persistence#4359

Draft
valentinewallace wants to merge 11 commits intolightningdevkit:mainfrom
valentinewallace:2026-01-reconstruct-htlcs-0.5
Draft

(0.5) Deprecate legacy pending HTLC ChannelManager persistence#4359
valentinewallace wants to merge 11 commits intolightningdevkit:mainfrom
valentinewallace:2026-01-reconstruct-htlcs-0.5

Conversation

@valentinewallace
Copy link
Contributor

@valentinewallace valentinewallace commented Jan 29, 2026

In LDK 0.3 we're adding support for reconstructing the ChannelManager's pending
forward HTLCs maps from channel data as part of removing the requirement to
regularly persist the manager, but til 0.5 we still would write/read those maps
within the manager to maintain compat with 0.2-. Also 0.3 adds a new field to
Channel that allowed the map reconstruction.

Once a few versions have passed, we have more confidence that the new field
is being written, so here we deprecate persistence of the old legacy maps and only
attempt to read them if the manager serialized version indicates that they were
written. We can also deprecate some other old codepaths, see commit messages.

Partially addresses #4286

Based on #4303

  • Test upgrading 0.2 -> 0.3/0.4 -> 0.5
  • Test downgrading 0.5 -> 0.3/4 -> 0.2
  • Update upgrade_downgrade_tests that currently upgrade from 0.2- to main, to upgrade to 0.3/0.4 instead (since 0.2- to 0.5 is unsupported)
  • Clean up clauded'd upgrade/downgrade tests
  • Update upgrade_downgrade_tests to not point to my branch once 0.3 is released

@valentinewallace valentinewallace added this to the 0.5 milestone Jan 29, 2026
@ldk-reviews-bot
Copy link

👋 Hi! I see this is a draft PR.
I'll wait to assign reviewers until you mark it as ready for review.
Just convert it out of draft status when you're ready for review!

@valentinewallace valentinewallace changed the title 2026 01 reconstruct htlcs 0.5 (0.5) Deprecate legacy pending HTLC ChannelManager persistence Jan 29, 2026
@valentinewallace valentinewallace added the blocked on next release Should Wait Until Next Release To Land label Jan 29, 2026
@codecov
Copy link

codecov bot commented Jan 29, 2026

Codecov Report

❌ Patch coverage is 80.52632% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.13%. Comparing base (3497b59) to head (492f5db).

Files with missing lines Patch % Lines
lightning/src/ln/channel.rs 74.73% 15 Missing and 9 partials ⚠️
lightning/src/ln/channelmanager.rs 86.17% 13 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #4359      +/-   ##
==========================================
+ Coverage   86.09%   86.13%   +0.03%     
==========================================
  Files         156      156              
  Lines      103623   103456     -167     
  Branches   103623   103456     -167     
==========================================
- Hits        89211    89108     -103     
+ Misses      11895    11854      -41     
+ Partials     2517     2494      -23     
Flag Coverage Δ
tests 86.13% <80.52%> (+0.03%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@valentinewallace valentinewallace force-pushed the 2026-01-reconstruct-htlcs-0.5 branch 2 times, most recently from 0350632 to 2170910 Compare February 6, 2026 23:03
@valentinewallace valentinewallace force-pushed the 2026-01-reconstruct-htlcs-0.5 branch from 2170910 to eb547f2 Compare February 12, 2026 22:54
In LDK 0.3 we added support for reconstructing the ChannelManager's pending
forward HTLCs maps from channel data as part of removing the requirement to
regularly persist the manager, but til now we still would write/read those maps
within the manager to maintain compat with 0.2-. Also 0.3 added a new field to
Channel that allowed the map reconstruction.

Now that a few versions have passed we have more confidence that the new field
is being written, here we deprecate persistence of the old legacy maps and only
attempt to read them if the manager serialized version indicates that they were
written.

Upcoming commits will ensure we error if the new field is missing.

XXX clean up claude tests
See previous commit, but now in prod reconstruct_manager_from_monitors will
always be set, so there's no need to have an option to set it in tests.
Used in the next commit when we log on some read errors.
In 0.3, we added a new field to Channel as part of adding support for
reconstructing the ChannelManager's pending forward HTLC set from
Channel{Monitor} data, moving towards removing the requirement of regularly
persisting the ChannelManager.

This new field cannot be set for HTLCs received pre-0.1 that are using this
legacy ::Resolved variant.

In this version, we fully rely on the new Channel field being set and cease
handling legacy HTLCs entirely, and thus must fully deprecate the ::Resolved
variant and require all inbound HTLCs be in state
InboundHTLCResolution::Pending, which we do here. Further cleanups are coming
in upcoming commits.
Previously, several variants of InboundHTLCState contained an
InboundHTLCResolution enum.  Now that the resolution enum only has one variant,
we can get rid of it and simplify the parent InboundHTLCState type.
This version of LDK no longer supports HTLCs created before 0.3, which allows
us to remove this variant that will only be present if an HTLC was received on
a pre-0.3 LDK version. See the past few commits.
In the previous commit, we removed the InboundHTLCResolution::Resolved enum
variant, which caused us to never provide any HTLCs in this now-removed
parameter.
We stopped adding any HTLCs to this vec a few commits ago when we removed
support for HTLCs that were originally received on LDK 0.1.
We stopped adding any HTLCs to this vec a few commits ago when we removed
support for HTLCs that were originally received on LDK 0.1
We stopped using this struct a few commits ago when we removed
support for HTLCs that were originally received on LDK 0.1.
@valentinewallace valentinewallace force-pushed the 2026-01-reconstruct-htlcs-0.5 branch from eb547f2 to 492f5db Compare February 13, 2026 22:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

blocked on next release Should Wait Until Next Release To Land

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants